home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / cat3 / GetSelect.3 < prev    next >
Text File  |  1994-09-20  |  4KB  |  133 lines
  1.  
  2.  
  3.  
  4. Tk_GetSelection(3)    Tk Library Procedures
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      Tk_GetSelection - retrieve the contents of the selection
  12.  
  13. SYNOPSIS
  14.      #include <tk.h>
  15.  
  16.      int
  17.      Tk_GetSelection(_i_n_t_e_r_p, _t_k_w_i_n, _t_a_r_g_e_t, _p_r_o_c, _c_l_i_e_n_t_D_a_t_a)
  18.  
  19. ARGUMENTS
  20.      Tcl_Interp      *_i_n_t_e_r_p      (in)      Interpreter  to   use
  21.                                             for reporting errors.
  22.  
  23.      Tk_Window       _t_k_w_i_n        (in)      Window    on    whose
  24.                                             behalf   to  retrieve
  25.                                             the selection (deter-
  26.                                             mines   display  from
  27.                                             which to retrieve).
  28.  
  29.      Atom            _t_a_r_g_e_t       (in)      Form  in   which   to
  30.                                             retrieve selection.
  31.  
  32.      Tk_GetSelProc   *_p_r_o_c        (in)      Procedure  to  invoke
  33.                                             to  process pieces of
  34.                                             the selection as they
  35.                                             are retrieved.
  36.  
  37.      ClientData      _c_l_i_e_n_t_D_a_t_a   (in)      Arbitrary    one-word
  38.                                             value   to   pass  to
  39.                                             _p_r_o_c.
  40. _________________________________________________________________
  41.  
  42.  
  43. DESCRIPTION
  44.      Tk_GetSelection retrieves the selection in the format speci-
  45.      fied  by _t_a_r_g_e_t.  The selection may actually be retrieved in
  46.      several pieces;  as each piece is retrieved, _p_r_o_c is  called
  47.      to process the piece.  _P_r_o_c should have arguments and result
  48.      that match the type Tk_GetSelProc:
  49.           typedef int Tk_GetSelProc(
  50.                ClientData _c_l_i_e_n_t_D_a_t_a,
  51.                Tcl_Interp *_i_n_t_e_r_p,
  52.                char *_p_o_r_t_i_o_n);
  53.      The _c_l_i_e_n_t_D_a_t_a and _i_n_t_e_r_p parameters to _p_r_o_c will be  copies
  54.      of  the corresponding arguments to Tk_GetSelection.  _P_o_r_t_i_o_n
  55.      will be a pointer to a string containing part or all of  the
  56.      selection.   For  large  selections,  _p_r_o_c  will  be  called
  57.      several times with sucessive portions of the selection.  The
  58.      X  Inter-Client  Communication Conventions Manual allows the
  59.      selection to be returned in formats other than strings, e.g.
  60.  
  61.  
  62.  
  63. Tk                                                              1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Tk_GetSelection(3)    Tk Library Procedures
  71.  
  72.  
  73.  
  74.      as  an array of atoms or integers.  If this happens, Tk con-
  75.      verts the selection back into a string before calling  _p_r_o_c.
  76.      If  the  selection is returned as an array of atoms, Tk con-
  77.      verts it to a string containing the atom names separated  by
  78.      white  space.   For any other format besides string, Tk con-
  79.      verts the  selection  to  a  string  containing  hexadecimal
  80.      values separated by white space.
  81.  
  82.      Tk_GetSelection returns to its caller when the selection has
  83.      been  completely  retrieved and processed by _p_r_o_c, or when a
  84.      fatal error has occurred (e.g. the  selection  owner  didn't
  85.      respond promptly).  Tk_GetSelection normally returns TCL_OK;
  86.      if an error occurs, it returns TCL_ERROR and leaves an error
  87.      message  in  _i_n_t_e_r_p->_r_e_s_u_l_t.  _P_r_o_c should also return either
  88.      TCL_OK or TCL_ERROR. If _p_r_o_c encounters an error in  dealing
  89.      with  the  selection,  it  should  leave an error message in
  90.      _i_n_t_e_r_p->_r_e_s_u_l_t and return TCL_ERROR;  this  will  abort  the
  91.      selection retrieval.
  92.  
  93.  
  94. KEYWORDS
  95.      format, get, selection retrieval
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129. Tk                                                              2
  130.  
  131.  
  132.  
  133.